Loadstar 248/248.d81/t.db+ doc 1

Text File | 2022-08-26 | 15KB | 582 lines

u

            DOTBASIC PLUS

         Program and Text by
      Dave Moorman and Lee Novak


    We at LOADSTAR are pleased to
offer the ultimate software develop-
ment package for the Commodore 64:
DotBASIC Plus. I need to thank Lee
Novak for Mr.Mouse 2.1, which is the
backbone of this unique Object
Oriented BASIC Extension. And a big
thanks goes to Jeff Jones for his help
in this project. Without it, DotBASIC
Plus would have been quite different.
He stopped Lee from making a couple of
BIG mistakes, and even some of his
ideas are among this mess of code.

    Programs written with DotBASIC
Plus automatically support both a
mouse in port 1 and a joystick in port
2. The FIRE button on the joystick is
the same as the left mouse button. For
joystick users, any key can be defined
to replace the missing right mouse
button. The middle button (on CMD's
SmartMouse) will double the mouse's
speed.

    DB+ automatically creates a boot
program (with a "B." prefix) that
loads all necessary files, and creates
a template DotBASIC program (with a
".DBS" extension) that will be your
main BASIC code. Also, MOUSE2.1 7K
1000 is copied to your work disk,
along with the DotBASIC ML code (with
a ".DML" extension).


 GETTING STARTED
 ---------------

    The DB+ development system will
work with one or two disk drives. With
two drives, you will put the DB+ disk
in one and your formated Work disk in
the other. Or, you can use a single
drive, and save your work to the DB+
disk for later copying to its own disk
(using your own file copier). Don't
forget to copy DB+ to a library disk
first! In this documentation, we will
use the variable DB to indicate the
DB+ drive and DW to indicate the Work
drive.

    LOAD"B.DOTBASIC",DB and RUN it.
You will be asked which drives your
disk(s) are on, followed by a Y/N
confirmation of each. Then you will
input the name of your project (no
extensions, please). The necessary
files are renamed to your project name
and copied to your Work drive. Then
your project is RUN. You will see the
mouse arrow for a second, then a READY
prompt in white. You are now ready to
program in DotBASIC Plus!


 FEATURES
 --------

    MV is now a system variable,
pointing to the start of the variable
zone, which is just a place where
certain user-accessible settings and
other data are held. You will use POKE
MV + OFFSET to change how some of the
commands work.

    Let's go over some of the features
of DB+. First off, the keyboard still
can mimic the mouse buttons.


  MV+14  Right Keycode    (F7 = 3)
  -----

    MV+14 holds the keyboard
equivalent to the right mouse button,
which is defined as F7, but you could
change it if you've assigned a
function to the right mouse button and
would like to use F7 (and F8) as
hotkeys instead.

    Note that MV+14 is not an ASCII
code. "Keycodes" are generated by the
SCNKEY routine during the interrupt.
They can be determined with this
one-line program:

   10 print peek(203):goto 10

    When you RUN it, hold down the key
you want to designate as a button and
note the number showing. Be aware that
keycodes are not affected by the
special (SHIFT/CMDR/CTRL) keys, and
these special keys don't have keycodes
- so they can't be used as mouse
buttons.

  MV+18 Keyboard Enable (default 129)
  -----
         +128 = Return can click
         +64  = Space can click
         +32  = Commodore can click.
         +1   = CRSR keys move arrow

    Even the CRSR keys can control the
arrow pointer around the screen. This
makes it especially easy to add
"keyboard support" to your programs
without having to think about it. By
default, the RETURN key serves as the
left mouse button.

    With a POKE, you could enable the
COMMODORE key to also serve as the
left mouse button. This would be
useful for any "click and drag"
situations within your program, only
because the Commodore key can be read
independently of the CRSR keys. It is
awkward to use, but it works. RETURN
or SPACE can be used to "click" the
rest of the time. It's more natural.


  ON and OFF
  ----------
  SYS DD -- ON
  .OF    -- OFF

    When you LIST your DBS program,
you will see SYS DD (DD=14336 -- the
beginning of the DB+ ML code) which
turns on DB+. It also sets the CPU-NMI
vector at $FFFA/B to point to an RTI.
This prevents a RESTORE-key crash
while the ROMs are out.

    .OF turns DB+ off. The old IRQ
vector is saved and later restored.

    SYS DD initializes the CAGE to
0,0,40,25 (the whole screen). It also
sets the variable MV+20 to 129. This
takes care of users who might break
out of your program during a menu,
since MV+20 and the cage usually have
different values during menus.


  MINOR CONSIDERATION
  -------------------

    When using a DB+ command after
THEN, you must precede it with a
colon:

 100 IF A=10 THEN:.BG,2


  EASY SPRITE
  -----------
  .QS
  .QR

    When DB+ is started, an arrow is
created (sprite at 46*256). You can
turn off the arrow and mouse control
at anytime with .QS, and turn it back
on with .QR. These names stand for IRQ
Suspend and IRQ Restore. The IRQ and
sprites are turned off with .QS and
restored with .QR. Occasionally, a
disk access command will turn off the
mouse. Use .QR to restore it.

    Sprite zero is enabled as a
regular-size, high resolution, white
mouse pointer with priority over the
background. You can use Sprite Edit
(soon to be released with the DB+
Package) to change the look of your
pointer.

   Related Variable:

  MV+17  Twin Flag   (default is 128)

    A Twin Flag setting of 128 (or
higher) will cause sprite 1 to be
enabled as a black shadow arrow. After
that, it is the interrupt's job to
ensure the shadow arrow follows the
other sprite. The Twin Flag may be set
to these values:

     0 = Single sprite only
   128 = Dual sprite,shadow  x+2,y+1
   192 = Dual sprite, perfect sync

    Although 192 would cause the
shadow sprite to be directly under the
pointer sprite, and thus unseen, there
ARE other uses for this feature. The
sprites don't have to share the same
shape, you know.


  ASK BASIC
  ---------
  .MA

    This crucial command is the only
way to get feedback from the mouse!
Feedback is deposited in integer
variables. Here's the wealth of
information you will get:

   Mouse position information

   PX%  Pixel-X location (0-319)
   PY%  Pixel-Y location (0-199)
   CX%  Cell-X location  (0-39)
   CY%  Cell-Y location  (0-24)

   Mouse button information

   L1%  Left button    (0=up, 1=down)
   R1%  Right button   (0=up, 1=down)
   L2%  New left push  (0=no, 1=yes)
   R2%  New right push (0=no, 1=yes)

    While L1% and R1% merely return
the state of the buttons, L2% and R2%
tell you if the press is NEW. This is
useful for clicking on things. There
are also other times when you want to
do something when the button is
pressed, but not continually as the
user holds the button down and scoots
across the screen.

    Internally, new button presses are
nulled when the button is lifted or
the .MA routine is called.

   Text screen information

   SC%  Screen Code under mouse
   CC%  Color Code under mouse
   PP%  Pointer Position of mouse

    The color data is stripped of its
upper (garbage) nybble. The pointer
position is the RAM location of the
screen cell right under the mouse.
Since PP% is an integer, values above
32767 will be negative.

   Region information

   RG%  Region # mouse is over (0-64)
   CR%  Region # being clicked (0-64)

    A "region" is an area of the
screen that you can define by its
X,Y,Width,Height limits. RG% will be
zero unless the mouse is currently
over an ACTIVE region. CR% will be
zero unless the user is currently
left-clicking on a particular region.
In the case of overlapping regions,
the higher number is returned.

    The "freshness" of all mouse
feedback depends on how often you are
able to use .MA, and how quickly your
program can respond to the data.


  LOOPING
  -------
  .DO
  .UN [true]
  .WH [true]

    For the sake of "freshness," DB+
has a very efficient Do-Loop method.
.DO marks the beginning of the loop
(in the processor stack -- somewhat
like a FOR-NEXT loop). The two other
commands, .UN and .WH are at the end
of the loop area.

  100 .DO:.MA:.UN L2%

     Th